<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>QuickFIX/J Installation</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link href="style.css" rel="stylesheet" type="text/css">
</head>

<body>
<div class="header">
<h1>QuickFIX/J User Manual</h1>
</div>
<h2>Installation and Building the Code.</h2>
<h3><a name="dependencies"></a>Runtime Dependencies</h3>
<h4>Java Virtual Machine:</h4>
<p>JVM compatible with Oracle JRE Java 1.7.x or higher.</p>

<h4>Required run-time libraries:</h4>

<p>
<em>(Note: The actual JAR files may have version numbers in them.)</em>
</p>

<table cellspacing="0" width="100%">
  <tr>
    <th>Library</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>The QFJ core JAR and message JARs.
    <ul>
    <li> quickfixj-core.jar
    <li> quickfixj-msg-fix40.jar
    <li> quickfixj-msg-fix41.jar
    <li> quickfixj-msg-fix42.jar
    <li> quickfixj-msg-fix43.jar
    <li> quickfixj-msg-fix44.jar
    <li> quickfixj-msg-fix50.jar
    <li> quickfixj-msg-fix50sp1.jar
    <li> quickfixj-msg-fix50sp2.jar
    </ul>
    or
    <ul>
    <li> quickfixj-all.jar (includes core and message JARs)
    </ul>
    </td>
    <td>QFJ runtime libraries</td>
  </tr>
</table>

<p></p>

<table cellspacing="0" width="100%">
  <tr>
    <th>Library</th>
    <th>Description</th>
  </tr>
  <tr>
    <td nowrap="nowrap">mina-core-2.0.16.jar</td>
    <td>Socket handling (Java NIO)</td>
  </tr>
  <tr>
    <td nowrap="nowrap">slf4j-api.jar</td>
    <td>SLF4J library for JDK logging.</td>
  </tr>
</table>

<h4>Optional run-time libraries:</h4>
<table cellspacing="0">
  <tr>
    <th>Library</th>
    <th>Description</th>
  </tr>
  <tr>
    <td nowrap="nowrap">log4j.jar</td>
    <td>If Log4J logging is desired. The JDK logging is the default.</td>
  </tr>
  <tr>
    <td nowrap="nowrap">slf4j-log4j12.jar</td>
    <td>Use this JAR file instead of slf4j-jdk14-*.jar if you want to
	use Log4J logging.</td>
  </tr>
  <tr>
    <td nowrap="nowrap">proxool.jar</td>
    <td>This JAR provided database connection pooling capabilities. It is required
		if you are using the JDBC store or log.</td>
  </tr>
  <tr>
    <td nowrap="nowrap">jcl104-over-slf4j.jar</td>
    <td>Adapts Jakarta Commons Logging to SLF4J. Required if you are using an optional
		library that depends on Jakarta Commons Logging. Currently, this includes Proxool
		(needed by JDBC store and log for connection pooling).</td>
  </tr>
  <tr>
    <td nowrap="nowrap">sleepycat-je.jar</td>
    <td>Needed if the SleepyCat JE message store is used.</td>
  </tr>
</table>

<p>
By default, the XML processing in QuickFIX/J uses the XML parser included
	with the JDK. In general other parsers can be used but it's possible you
	will have problems. We've had users report that Xerces 2.6 does not work,
	but that version 2.8 does. If you try other parsers, please let us know if it
	works or not.
</p>

<h2><a name="build"></a>Building QuickFIX/J</h2>

<p><em>These instructions are for developers who don't want
    to use the prebuilt binaries or are intending to modify and rebuild the QuickFIX/J
    code. </em>If you are building the code from the command line you'll need
    to download and install Maven (version 3.2.5 or newer). If you are building from
    an IDE, Maven is usually included.

<em>Building from source requires Java 7+.</em>

</p>
<ol>
  <li>Check out the code from GitHub.
      See the <a href="https://help.github.com/articles/which-remote-url-should-i-use/">instructions</a> at
      GitHub for more details on cloning the repository.</li>
  <li>Change directory to the top-level directory of the checked out code. You
    should see a pom.xml file.</li>
  <li>Run <code>mvn package</code> to build the QuickFIX/J and examples jar files.
    This will also generate all the FIX message-related code for the various
    FIX versions.</li>
  <li>There is an option for the code generator to use BigDecimal instead of double for fields like price and quantity.
      To enable this feature pass a <code>-Dgenerator.decimal</code> option on the command line when
      running the <code>generate.code</code> target.</li>
</ol>
<h3>Command-line Switches</h3>
There are various command-line switches you can pass to ant to modify the produced behavior:
<table cellspacing="0" width="100%">
  <tr>
    <th>Switch</th>
    <th>Description</th>
    <th>Default</th>
  </tr>
  <tr>
    <td nowrap="nowrap">-Dgenerator.decimal</td>
    <td>Generate BigDecimal vs doubles fields</td>
    <td>false</td>
  </tr>
  <tr>
    <td nowrap="nowrap">-DskipAT=true</td>
    <td>Skip running of acceptance test suite.</td>
    <td>false</td>
  </tr>
</table>
<p>
  For example, in order to generate fields with BigDecimals and skip acceptance tests:<br>
<code>mvn test -Dgenerator.decimal=true -DskipAT=true</code>
</p>
<h3>IDE support:</h3>
<p>There are
  Eclipse and Netbeans project definition files in the top-level directory of the checked out directory.

   <em style="color:red">When the project is first created, it will not have the generated message classes
   and compile errors will occur!</em> Best is to compile once on the command line before importing
   the project into the IDE.

<h3>Maven Integration:</h3>
<p>If you are using the <a href="http://maven.apache.org">Maven</a> build system, you can reference
    the pre-built QuickFIX/J libraries hosted at the <a href="http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22org.quickfixj%22">Central Repository</a>
    repository.</p>
<p> Add the following to your <em>dependencies</em> section, with appropriate modifications based on
        the logging subsystem you choose:<br>
        <pre class="code">
&lt;!-- QuickFIX/J dependencies --&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-core&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-messages-fix40&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-messages-fix41&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-messages-fix42&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-messages-fix43&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.quickfixj&lt;/groupId&gt;
    &lt;artifactId&gt;quickfixj-messages-fix44&lt;/artifactId&gt;
    &lt;version&gt;2.0.0&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
    &lt;artifactId&gt;slf4j-log4j12&lt;/artifactId&gt;
    &lt;version&gt;1.7.22&lt;/version&gt;
&lt;/dependency&gt;
&lt;dependency&gt;
    &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
    &lt;artifactId&gt;slf4j-api&lt;/artifactId&gt;
    &lt;version&gt;1.7.22&lt;/version&gt;
&lt;/dependency&gt;</pre>
</p>

<h2><a name="database"></a>Generating the database for JDBC based store and log</h2>
<p> Everything needed to generate your database is in the <a href="https://github.com/quickfix-j/quickfixj/tree/master/quickfixj-core/src/main/resources/config/sql"> src/main/resources/config/sql</a> subdirectories.
  For MySQL, there are the script and batch files <code>create_mysql.sh</code> and <code>create_mysql.bat</code>.
  These scripts will work on a newly installed mysql database with default permisions.
  The scripts will try to generate the database using the root MySQL account
  with no password. If you need to use a different account or need a password,
  you will have to edit the script. To select a different user, simply change
  'root' to another user. To add a password, use pass the -p option after the
username. Similar scripts are provided for MSSQL, PostgreSQL and Oracle.
</p>
<h3><a name="oracle">Special notes for Oracle</h3>
<p>
Oracle treats empty strings as null values. Null values are not allowed for primary key
fields. The fields used in the primary keys are:
<ul>
	<li>beginstring
	<li>sendercompid
	<li>targetcompid
	<li>session_qualifier
	<li>msgseqnum
</ul>
If any of these keys contains an empty string, null constraint violations will occur.
Therefore, the session_qualifier has been set to a non-empty string for Oracle.
</p>
<p>
Please also not, that for string fields always the VARCHAR2 data type should be used.
If CHAR fields are used, they always have to be spaced-padded to the full length.
</p>
<h2><a name="testing"></a>Testing QuickFIX/J</h2>
<p> The development of QuickFIX has been driven by a suite of functional acceptance
  tests and unit tests. We have been working incrementally, functional test by
  functional test, writing the unit tests before the code. If these tests pass,
we're reasonably confident that the engine works as intended.</p>
<p>The developer unit tests are written as JUnit tests and test the code directly.
  The functional acceptance tests are scripted FIX messages that are
  pumped
  into a running FIX server. Most of these tests are based off of the FIX Session-level
  Test Cases and Expected Behaviors document.</p>
<p>The unit tests can be run by running the <code>test</code> target
  in the pom.xml file. If you are using Eclipse, you can right-click on
  the quickfix package in the test subdirectory and select the &quot;Run as... -&gt;
  JUnit Test&quot; option. This should locate all the unit tests in the package hierarchy
  and run them in the integrated JUnit test runner.</p>
<h3>Acceptance Tests</h3>
<p> QuickFIX/J also has a scriptable test runner that comes with a series of
  automated acceptance test. The basic tests that come with QuickFIX are based
  off of the <a href="http://www.fixprotocol.org/ORGANIZATIONS/928202077/FIX_TestCase_SessionLevel20010710.doc"> FIX
  Session-level Test Cases and Expected Behaviors</a> document produced by the
  FIX protocol organization. These tests verify that QuickFIX adheres to the
  FIX specifications. The automated nature of these tests guarantees that future
releases of QuickFIX will not break any current functionality. </p>
<p> Perhaps even more importantly is how these test are used to drive the development
  of QuickFIX. Before a line of code is written in support of a protocol feature,
  one of these tests is written. This test first approach sets up a goal for
  developers who will have objective verification that they correctly implemented
  the standard. </p>
<p>To run the acceptance tests:
  If you are using Eclipse, right-click on the <code>quickfix.test.acceptance.AcceptanceTestSuite</code>  class
  and select the &quot;Run as... -&gt; JUnit Test&quot; option. This will start an acceptance
  test program with an embedded QuickFIX/J server, load the AT definition files
  and convert them to JUnit tests, and run those tests in the embedded JUnit
  test view.</p>
<h4>Writing your own Acceptance Test Scripts</h4>
<p> Below is an example of a test script that tests the engines behavior when
  it receives a NewSeqNo value that is less than the expected MsgSeqNum. </p>

<pre class="code">
  iCONNECT
  I8=FIX.4.2&#x2401;35=A&#x2401;34=1&#x2401;49=TW&#x2401;52=&lt;time&gt;&#x2401;56=ISLD&#x2401;98=0&#x2401;108=30&#x2401;
  E8=FIX.4.2&#x2401;9=57&#x2401;35=A&#x2401;34=1&#x2401;49=ISLD&#x2401;52=00000000-00:00:00&#x2401;56=TW&#x2401;98=0&#x2401;108=30&#x2401;10=0&#x2401;

  # sequence reset without gap fill flag (default to N)
  I8=FIX.4.2&#x2401;35=4&#x2401;34=0&#x2401;49=TW&#x2401;52=&lt;time&gt;&#x2401;56=ISLD&#x2401;36=1&#x2401;
  E8=FIX.4.2&#x2401;9=112&#x2401;35=3&#x2401;34=2&#x2401;49=ISLD&#x2401;52=00000000-00:00:00&#x2401;56=TW&#x2401;45=0&#x2401;58=Value is incorrect (out of range) for this tag&#x2401;372=4&#x2401;373=5&#x2401;10=0&#x2401;

  I8=FIX.4.2&#x2401;35=1&#x2401;34=2&#x2401;49=TW&#x2401;52=&lt;time&gt;&#x2401;56=ISLD&#x2401;112=HELLO&#x2401;
  E8=FIX.4.2&#x2401;9=55&#x2401;35=0&#x2401;34=3&#x2401;49=ISLD&#x2401;52=00000000-00:00:00&#x2401;56=TW&#x2401;112=HELLO&#x2401;10=0&#x2401;

  # sequence reset without gap fill flag (default to N)
  I8=FIX.4.2&#x2401;35=4&#x2401;34=0&#x2401;49=TW&#x2401;52=&lt;time&gt;&#x2401;56=ISLD&#x2401;36=1&#x2401;123=N&#x2401;
  E8=FIX.4.2&#x2401;9=112&#x2401;35=3&#x2401;34=4&#x2401;49=ISLD&#x2401;52=00000000-00:00:00&#x2401;56=TW&#x2401;45=0&#x2401;58=Value is incorrect (out of range) for this tag&#x2401;372=4&#x2401;373=5&#x2401;10=0&#x2401;

  I8=FIX.4.2&#x2401;35=1&#x2401;34=3&#x2401;49=TW&#x2401;52=&lt;time&gt;&#x2401;56=ISLD&#x2401;112=HELLO&#x2401;
  E8=FIX.4.2&#x2401;9=55&#x2401;35=0&#x2401;34=5&#x2401;49=ISLD&#x2401;52=00000000-00:00:00&#x2401;56=TW&#x2401;112=HELLO&#x2401;10=0&#x2401;
  iDISCONNECT
  </pre>
In these script there are two types of commands, action commands and messages
commands. Action commands begin with lowercase letters while message command
begin with uppercase letters.
<h4>Action Commands</h4>
<b>i&lt;ACTION&gt;</b> - initiates an action<br>
<b>e&lt;ACTION&gt;</b> - expect (wait for) an action<br>
<br>
Supported actions are:<br>
<br>
<b>iCONNECT</b> - initiate connection to a FIX acceptor<br>
<b>eCONNECT</b> - expect a connection from a FIX initiator<br>
<b>iDISCONNECT</b> - initiate a disconnect<br>
<b>eDISCONNECT</b> - expect a disconnect<br>
<br>
<h3>Message Commands</h3>
<b>I&lt;MESSAGE&gt;</b> - initiate (send) a message<br>
<b>E&lt;MESSAGE&gt;</b> - expect (wait for) a message<br>
<br>
<p> When using the <b>I</b> command, you do not need to add the <i>Length(9)</i> or
  the <i>CheckSum(10)</i> fields, they will be added for you with the correct
  values in the appropriate locations. The only time you would add these fields
  is if you intentionally wish to make them incorrect. </p>
<p> The <b>I</b> command also provides a TIME macros for fields. By setting a
  field equal to &lt;TIME&gt;, the current system time will be placed in the
  field. (i.e. 52=&lt;time&gt;). You can also use offsets such as 52=&lt;TIME-120> or
  52=&lt;TIME+15> in order to set the time plus or minus some seconds from the
  current time. </p>
<p>The <b>E</b> command verifies that you have received the correct message.
  This command will compare the values of each field to make sure they are correct.
  Some fields cannot be verified deterministically before run-time such as the
  SendingTime and CheckSum fields. These fields can be added to the <i>fields.fmt</i> file
  where a regular expression can be defined to at least verify the field is in
  the correct format. For example: </p>
  <p>
10=\d{3}, checksum must be exactly three digits<br>
52=\d{8}-\d{2}:\d{2}:\d{2}, sending time must be in the form of DDDDDDDD-DD:DD:DD
where D is a digit.
</p>

<div class="footer">More information at <a href="http://www.quickfixj.org/">www.quickfixj.org</a></div>

</body>
</html>
